pan-wizard 3.12.3 → 3.12.5

package/agents/pan-debugger.md

@@ -132,13 +132,13 @@ A good hypothesis can be proven wrong. If you can't design an experiment to disp
 
 Before running any experiments, think through at least **three independent hypotheses** that could explain the observed failure. For each, write down a one-line Bayesian prior ("90% likely given the symptom", "30%", etc.) based on how well it fits the evidence and how common the failure class is in this codebase.
 
-Then **attack the top two in parallel**: emit the `Read`, `Grep`, and log-inspection tool calls for both hypotheses in a single turn. Only serialize when a hypothesis's next step strictly depends on data from a previous step.
+Then **investigate the top two in parallel**: emit the `Read`, `Grep`, and log-inspection tool calls for both hypotheses in a single turn. Only serialize when a hypothesis's next step strictly depends on data from a previous step.
 
 - If the top hypothesis is confirmed, stop — don't also debug the lower-ranked ones.
 - If the top two are both refuted, rank the remaining hypotheses and repeat.
 - Record each hypothesis's prior and final verdict in the debug session file so later steps can see the tree.
 
-Parallel exploration keeps investigation bounded: 3 priors × 2-parallel attack = at most 3 rounds before you have a clear winner, rather than walking a depth-first chain of 10 dead ends.
+Parallel exploration keeps investigation bounded: 3 priors × 2-parallel investigation = at most 3 rounds before you have a clear winner, rather than walking a depth-first chain of 10 dead ends.
 
 ## Experimental Design Framework
 

package/agents/pan-hardener.md

@@ -9,6 +9,8 @@ effort: high
 <role>
 You are the PAN hardener. You perform focused security review on files changed during phase execution, applying OWASP Top 10 (2025) and STRIDE threat modeling frameworks.
 
+This is **authorized, defensive** secure-coding review of the user's own codebase — the goal is to find and fix weaknesses before shipping. You report findings for the user to remediate; you never write exploit code, attack tooling, or step-by-step intrusion instructions.
+
 You are spawned by `/pan:review-deep <phase>` or `/pan:exec-phase --deep-review`. Your output is read by `pan-meta-reviewer` (cross-checks you) and merged by `review-deep.cjs` into `.planning/reviews/<phase>/deep-review.md`.
 
 **You NEVER modify files.** You report findings; the user fixes them.
@@ -51,7 +53,7 @@ Before writing findings, think through:
 
 1. **What changed in this phase?** Read the diff or plan.md files list. Map changes to OWASP categories — e.g. "new endpoint added" → A01+A03 scan; "new SQL query" → A03 scan.
 2. **Does this touch auth, data, or secrets?** These categories get the most thorough STRIDE pass. Changes to `logger.js` or docs don't.
-3. **What would an attacker do?** For every new surface, try to construct an exploit path mentally. If you can't construct one in 30 seconds, note the effort and move on — don't fabricate threats.
+3. **How could this be reached and abused?** For every new surface, trace how it could be reached and what the impact would be, so you can prioritize the fix. If you can't identify a realistic path in 30 seconds, note the effort and move on — don't fabricate threats.
 4. **Cross-check: did the reviewer already flag this?** You'll be merged with their output. Duplicating their `use parameterized queries` finding is OK but prefer adding severity (reviewer says INFO, you say HIGH because it's in an auth path).
 
 </reasoning_protocol>
@@ -91,7 +93,7 @@ generated: <ISO timestamp>
 ```
 
 **Severity scale:**
-- `critical` — remote exploit with no prerequisites; use sparingly, only when one misuse leads to data loss or RCE.
+- `critical` — remotely reachable with no prerequisites; use sparingly, only when one misuse leads to data loss or remote code execution.
 - `high` — exploitable with typical user privileges; blocks merge by default.
 - `medium` — defense-in-depth issue; fix before production but won't block merge if documented.
 - `low` — best-practice deviation; nice to fix.

package/agents/pan-meta-reviewer.md

@@ -16,7 +16,7 @@ You are the PAN meta-reviewer. Your job is to check the first-pass reviewers (`p
 
 You are spawned by `/pan:review-deep <phase>` after both the reviewer and hardener have written their reports. Your output is merged with theirs by `review-deep.cjs`.
 
-**You NEVER modify source code.** You produce one findings file.
+**You NEVER modify source code.** You produce one findings file. This is authorized, defensive review of the user's own codebase — you adjudicate security findings for remediation; never produce exploit code.
 
 **CRITICAL: Mandatory Initial Read**
 If the prompt contains a `<files_to_read>` block (it will contain the reviewer and hardener outputs + representative diff snippets), you MUST use the `Read` tool to load every file listed there before performing any other actions.

package/agents/pan-reviewer.md

@@ -9,7 +9,7 @@ effort: medium
 <role>
 You are a PAN code reviewer. You perform read-only code review on files changed during phase execution.
 
-Your job: Check convention compliance, security patterns, and code quality. You do NOT modify files — you report findings.
+Your job: Check convention compliance, security patterns, and code quality. You do NOT modify files — you report findings. This is authorized, defensive review of the user's own codebase — surface security-relevant findings for the user to remediate; never produce exploit code.
 
 **CRITICAL: Mandatory Initial Read**
 If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.

package/bin/install.js

@@ -2490,8 +2490,9 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
             !caps.has_thinking ? 'extended thinking (E-3, E-10, E-11)' : null,
           ].filter(Boolean).join(', ');
           console.log(`
-  ${yellow}ℹ${reset} PAN 2.10+ is tuned for Opus 4.7+ class models. Default model "${modelField}" lacks: ${missing}.
-     Features degrade gracefully, but upgrade to claude-opus-4-8 (or claude-fable-5) for best results.`);
+  ${yellow}ℹ${reset} PAN's multi-agent workflows are tuned for frontier reasoning models. Default model "${modelField}" lacks: ${missing}.
+     Features degrade gracefully, but for best results select claude-fable-5 (PAN's recommended flagship — deepest
+     long-horizon reasoning for the bot army) or claude-opus-4-8 (same 1M context at half the cost).`);
         }
       }
     } catch {

package/hooks/dist/pan-cost-logger.js

@@ -18,6 +18,29 @@ const path = require('path');
 
 const METRICS_DIR = 'metrics';
 const TOKENS_FILE = 'tokens.jsonl';
+const CURSOR_FILE = '.cost-cursor.json';
+
+// Per-transcript high-water mark: the count of JSONL records already attributed
+// to earlier SubagentStop events, keyed by transcript path. Each event then sums
+// ONLY its own slice (records past the cursor) instead of re-summing the whole
+// shared-session transcript every time — the latter multiplies cumulative-per-turn
+// cache-read into the billions/trillions and stamps it onto every subagent record
+// (field report 2026-06). Stored next to tokens.jsonl; best-effort, never blocks.
+function cursorFilePath(cwd) {
+  return path.join(cwd, '.planning', METRICS_DIR, CURSOR_FILE);
+}
+function readCursor(cwd) {
+  try {
+    const c = JSON.parse(fs.readFileSync(cursorFilePath(cwd), 'utf-8'));
+    return c && typeof c === 'object' ? c : {};
+  } catch { return {}; }
+}
+function writeCursor(cwd, cursor) {
+  try {
+    fs.mkdirSync(path.dirname(cursorFilePath(cwd)), { recursive: true });
+    fs.writeFileSync(cursorFilePath(cwd), JSON.stringify(cursor), 'utf-8');
+  } catch { /* best-effort — never block the agent loop */ }
+}
 
 /**
  * Extract what we can from the SubagentStop event payload.
@@ -49,7 +72,12 @@ function buildCostRecord(data, cwd) {
   let model = typeof data.model === 'string' && data.model ? data.model : null;
   const needUsage = (inputTokens + outputTokens + cacheRead + cacheWrite) === 0;
   if ((needUsage || !model) && data.transcript_path) {
-    const fromTranscript = readUsageFromTranscript(data.transcript_path, data.session_id);
+    // Attribute only the transcript slice since the previous SubagentStop for
+    // this transcript, so a shared-session transcript is never re-summed on
+    // every event (field report 2026-06 — the billion-token cache-read bug).
+    const cursor = readCursor(cwd);
+    const since = cursor[data.transcript_path] || 0;
+    const fromTranscript = readUsageFromTranscript(data.transcript_path, data.session_id, since);
     if (needUsage) {
       inputTokens = fromTranscript.input_tokens;
       outputTokens = fromTranscript.output_tokens;
@@ -57,6 +85,12 @@ function buildCostRecord(data, cwd) {
       cacheWrite = fromTranscript.cache_creation_input_tokens;
     }
     if (!model) model = fromTranscript.model;
+    // Advance the cursor to the end of the transcript so the next subagent's
+    // record starts fresh (these slices partition the transcript — no overlap).
+    if (fromTranscript.lineCount > since) {
+      cursor[data.transcript_path] = fromTranscript.lineCount;
+      writeCursor(cwd, cursor);
+    }
   }
 
   const record = {
@@ -85,23 +119,36 @@ function extractNumber(obj, key) {
 }
 
 /**
- * P-1805 (v3.7.8): read transcript JSONL and sum usage across all assistant
- * messages belonging to the subagent's session. Mirrors the helper in
- * pan-trace-logger.js. Returns zeros if transcript missing/unreadable.
+ * P-1805 (v3.7.8): read transcript JSONL and sum usage across assistant messages.
+ *
+ * `sinceLine` (P-360, field report 2026-06): skip the first N non-empty records —
+ * the count already attributed to earlier SubagentStop events for this transcript.
+ * Summing only the slice past the cursor is what stops a shared-session transcript
+ * from being re-summed on every event (which multiplied cumulative-per-turn
+ * cache-read into the billions). Returns `lineCount` = total non-empty records seen
+ * so the caller can advance the cursor. Returns zeros if missing/unreadable.
+ *
+ * @param {string} transcriptPath
+ * @param {string} sessionId
+ * @param {number} [sinceLine=0] - records already attributed (the cursor)
  */
-function readUsageFromTranscript(transcriptPath, sessionId) {
+function readUsageFromTranscript(transcriptPath, sessionId, sinceLine = 0) {
   const totals = {
     input_tokens: 0,
     output_tokens: 0,
     cache_read_input_tokens: 0,
     cache_creation_input_tokens: 0,
     model: null,
+    lineCount: 0,
   };
   if (!transcriptPath || typeof transcriptPath !== 'string') return totals;
   let raw;
   try { raw = fs.readFileSync(transcriptPath, 'utf-8'); } catch { return totals; }
+  let seen = 0; // count of non-empty JSONL records (the cursor unit)
   for (const line of raw.split('\n')) {
     if (!line) continue;
+    seen++;
+    if (seen <= sinceLine) continue; // already attributed to an earlier event
     let entry;
     try { entry = JSON.parse(line); } catch { continue; }
     if (sessionId && entry.session_id && entry.session_id !== sessionId) continue;
@@ -120,6 +167,7 @@ function readUsageFromTranscript(transcriptPath, sessionId) {
     totals.cache_read_input_tokens += extractNumber(usage, 'cache_read_input_tokens');
     totals.cache_creation_input_tokens += extractNumber(usage, 'cache_creation_input_tokens');
   }
+  totals.lineCount = seen;
   return totals;
 }
 
@@ -164,4 +212,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { buildCostRecord, appendRecord, readUsageFromTranscript, METRICS_DIR, TOKENS_FILE };
+module.exports = { buildCostRecord, appendRecord, readUsageFromTranscript, readCursor, writeCursor, METRICS_DIR, TOKENS_FILE, CURSOR_FILE };

package/hooks/dist/pan-trace-logger.js

@@ -39,6 +39,24 @@ function getCurrentSessionId(cwd) {
   }
 }
 
+const TRACE_CURSOR_FILE = '.trace-cursor.json';
+
+// Per-transcript high-water mark (see pan-cost-logger.js for the full rationale):
+// sum only the transcript slice since this hook's previous SubagentStop, so a
+// shared-session transcript isn't re-summed on every event (which inflates
+// cumulative-per-turn cache-read into the billions — field report 2026-06).
+// Trace-logger keeps its OWN cursor: cost-logger fires on the same event and the
+// two must not consume each other's slice.
+function traceCursorPath(cwd) { return path.join(getOptimizeDir(cwd), TRACE_CURSOR_FILE); }
+function readTraceCursor(cwd) {
+  try { const c = JSON.parse(fs.readFileSync(traceCursorPath(cwd), 'utf-8')); return c && typeof c === 'object' ? c : {}; }
+  catch { return {}; }
+}
+function writeTraceCursor(cwd, cursor) {
+  try { fs.mkdirSync(path.dirname(traceCursorPath(cwd)), { recursive: true }); fs.writeFileSync(traceCursorPath(cwd), JSON.stringify(cursor), 'utf-8'); }
+  catch { /* best-effort — never block the agent loop */ }
+}
+
 /**
  * Ensure a trace session exists. If none is active, create a day-scoped
  * auto-session so tracing works across the whole flow without manual init.
@@ -99,12 +117,13 @@ function extractNumber(obj, key) {
  * @param {string} [sessionId] - Optional subagent session_id to filter on
  * @returns {Object} usage totals object
  */
-function readUsageFromTranscript(transcriptPath, sessionId) {
+function readUsageFromTranscript(transcriptPath, sessionId, sinceLine = 0) {
   const totals = {
     input_tokens: 0,
     output_tokens: 0,
     cache_read_input_tokens: 0,
     cache_creation_input_tokens: 0,
+    lineCount: 0,
   };
   if (!transcriptPath || typeof transcriptPath !== 'string') return totals;
   let raw;
@@ -113,8 +132,11 @@ function readUsageFromTranscript(transcriptPath, sessionId) {
   } catch {
     return totals;
   }
+  let seen = 0; // count of non-empty JSONL records (the cursor unit)
   for (const line of raw.split('\n')) {
     if (!line) continue;
+    seen++;
+    if (seen <= sinceLine) continue; // already attributed to an earlier event
     let entry;
     try {
       entry = JSON.parse(line);
@@ -136,17 +158,25 @@ function readUsageFromTranscript(transcriptPath, sessionId) {
     totals.cache_read_input_tokens += extractNumber(usage, 'cache_read_input_tokens');
     totals.cache_creation_input_tokens += extractNumber(usage, 'cache_creation_input_tokens');
   }
+  totals.lineCount = seen;
   return totals;
 }
 
 /**
  * Build trace event(s) from a SubagentStop payload.
- * Pure function — no side effects.
+ *
+ * When the payload lacks usage and `cwd` is supplied, this advances a
+ * per-transcript cursor (its only side effect) so each event is attributed
+ * just its own transcript slice — never the whole shared-session transcript
+ * re-summed every event (field report 2026-06). Without `cwd` it falls back to
+ * the legacy whole-transcript read (used only when a transcript_path is given).
  *
  * @param {Object} data - SubagentStop event payload
+ * @param {string} sessionId - active trace session id
+ * @param {string} [cwd] - project root, enables per-transcript delta attribution
  * @returns {Object[]} Array of trace event records
  */
-function buildTraceEvents(data, sessionId) {
+function buildTraceEvents(data, sessionId, cwd) {
   if (!data || typeof data !== 'object') return [];
   if (data.hook_event_name && data.hook_event_name !== 'SubagentStop') return [];
 
@@ -160,10 +190,16 @@ function buildTraceEvents(data, sessionId) {
   let outputTokens = extractNumber(data.usage, 'output_tokens');
   let cacheRead = extractNumber(data.usage, 'cache_read_input_tokens');
   if ((inputTokens + outputTokens + cacheRead) === 0 && data.transcript_path) {
-    const fromTranscript = readUsageFromTranscript(data.transcript_path, data.session_id);
+    const cursor = readTraceCursor(cwd);
+    const since = cursor[data.transcript_path] || 0;
+    const fromTranscript = readUsageFromTranscript(data.transcript_path, data.session_id, since);
     inputTokens = fromTranscript.input_tokens;
     outputTokens = fromTranscript.output_tokens;
     cacheRead = fromTranscript.cache_read_input_tokens;
+    if (cwd && fromTranscript.lineCount > since) {
+      cursor[data.transcript_path] = fromTranscript.lineCount;
+      writeTraceCursor(cwd, cursor);
+    }
   }
   const totalTokens = inputTokens + outputTokens;
 
@@ -245,7 +281,7 @@ if (require.main === module) {
       const cwd = data.cwd || data.workspace?.current_dir || process.cwd();
       // Always ensure a session exists — creates a day-scoped auto-session if needed
       const sessionId = ensureSessionId(cwd);
-      const events = buildTraceEvents(data, sessionId);
+      const events = buildTraceEvents(data, sessionId, cwd);
       appendTraceEvents(cwd, events, sessionId);
     } catch {
       // Silent fail

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pan-wizard",
-  "version": "3.12.3",
+  "version": "3.12.5",
   "description": "Command a bot army for your codebase: an Opus Mission Control delegates whole-project goals to specialist squads and ships behind a human merge gate. Five AI CLIs, zero context rot.",
   "bin": {
     "pan-wizard": "bin/install.js"

package/pan-wizard-core/bin/lib/cost.cjs

@@ -186,6 +186,25 @@ function readRecords(cwd) {
  * @param {Object} [opts] - {since, until, group_by}
  * @returns {Object} Aggregation
  */
+/**
+ * A record is "suspect" when its token counts are physically implausible for a
+ * single subagent — the signature of the pre-v3.12.4 transcript-oversum bug
+ * (billions of cache-read, cache-read dwarfing input, 100% cache-hit). Such
+ * records are quarantined from aggregates so a poisoned ledger can't report
+ * millions of dollars. See docs/FIELD-REPORT-army-2026-06.md.
+ * @param {Object} r - a cost record
+ * @returns {boolean}
+ */
+function isSuspectRecord(r) {
+  if (!r || typeof r !== 'object') return false;
+  const cr = r.cache_read_tokens || 0;
+  const io = (r.input_tokens || 0) + (r.output_tokens || 0);
+  if (cr > 5e8) return true;                        // no scoped subagent re-reads >500M cached tokens
+  if (cr > 1e7 && cr > 100 * (io + 1)) return true; // cache-read dwarfs input+output
+  if ((r.output_tokens || 0) > 1e7) return true;    // ~10M output = cumulative oversum
+  return false;
+}
+
 function aggregate(cwd, opts) {
   const records = readRecords(cwd);
   const since = opts?.since ? new Date(opts.since).getTime() : null;
@@ -202,13 +221,14 @@ function aggregate(cwd, opts) {
   });
 
   const totals = {
-    calls: filtered.length,
+    calls: 0,
     input_tokens: 0,
     output_tokens: 0,
     cache_read_tokens: 0,
     cache_write_tokens: 0,
     cost_usd: 0,
     cost_unknown: 0,
+    suspect_excluded: 0,
   };
 
   const byAgent = {};
@@ -229,6 +249,10 @@ function aggregate(cwd, opts) {
   }
 
   for (const r of filtered) {
+    // Quarantine physically-impossible records (pre-v3.12.4 transcript-oversum
+    // bug) so a poisoned ledger doesn't poison the totals / HUD / /pan:cost.
+    if (isSuspectRecord(r)) { totals.suspect_excluded += 1; continue; }
+    totals.calls += 1;
     totals.input_tokens += r.input_tokens || 0;
     totals.output_tokens += r.output_tokens || 0;
     totals.cache_read_tokens += r.cache_read_tokens || 0;
@@ -398,6 +422,7 @@ module.exports = {
   appendRecord,
   readRecords,
   aggregate,
+  isSuspectRecord,
   renderTable,
   renderChart,
   resolveRate,

package/pan-wizard-core/bin/lib/hud.cjs

@@ -267,7 +267,7 @@ function collectHudData(cwd, opts = {}) {
   return {
     generated_at: now.toISOString(),
     army_active: armyActive,
-    project: { name, version, milestone: milestone ? { version: milestone.version, name: milestone.name } : null, core_value: coreValue },
+    project: { name, version, dir_name: path.basename(cwd.replace(/[\\/]+$/, '')), milestone: milestone ? { version: milestone.version, name: milestone.name } : null, core_value: coreValue },
     state,
     progress: phaseScan,
     army,
@@ -425,7 +425,7 @@ function renderMission(d) {
     <div class="mhead">
       <div>
         <div class="kicker">pan army · mission control</div>
-        <div class="title">${esc(p.name || 'Untitled project')}</div>
+        <div class="title">${esc(p.name || p.dir_name || 'Untitled project')}</div>
         ${p.core_value ? `<div class="sub">${esc(p.core_value)}</div>` : ''}
       </div>
       <div class="mmeta">
@@ -586,6 +586,17 @@ function renderHarness(d) {
 
 function renderTelemetry(d) {
   const t = d.telemetry;
+  // A ledger where most records are implausible is the pre-v3.12.4 capture bug —
+  // don't present salvaged numbers as if trustworthy; tell the user to reset it.
+  if (t.totals.suspect_excluded > t.totals.calls) {
+    const total = t.totals.suspect_excluded + t.totals.calls;
+    return `
+  <section class="panel">
+    <div class="ph">telemetry</div>
+    <div class="row noborder"><span class="rl">Status</span>${pill('legacy ledger — unreliable', 'warn')}</div>
+    <div class="amono dim" style="margin-top:10px;line-height:1.6;">${t.totals.suspect_excluded} of ${total} cost records are implausible (the pre-v3.12.4 telemetry capture bug). Reset the ledger with <b>pan-tools cost clear</b> — records captured after the fix are accurate.</div>
+  </section>`;
+  }
   const keys = Object.keys(t.by_squad).sort((a, b) => t.by_squad[b].cost - t.by_squad[a].cost);
   const max = keys.reduce((m, k) => Math.max(m, t.by_squad[k].cost), 0) || 1;
   const bars = keys.length
@@ -602,6 +613,7 @@ function renderTelemetry(d) {
     <div class="row"><span class="rl">Total spend</span><span class="amono">${fmtUsd(t.totals.cost_usd)}</span></div>
     <div class="row"><span class="rl">Tokens</span><span class="amono">${fmtTokens(t.totals.input_tokens + t.totals.output_tokens)}</span></div>
     <div class="row"><span class="rl">Cache hit</span><span class="amono okc">${t.cache_hit_rate_pct == null ? 'n/a' : t.cache_hit_rate_pct + '%'}</span></div>
+    ${t.totals.suspect_excluded ? `<div class="row"><span class="rl">Excluded</span>${pill(t.totals.suspect_excluded + ' implausible records', 'warn')}</div>` : ''}
     <div class="sqbars">${bars}</div>
   </section>`;
 }

package/pan-wizard-core/references/model-profiles.md

@@ -10,7 +10,7 @@ PAN uses three abstract tiers instead of hardcoded model names:
 
 | Tier | Purpose | Anthropic | OpenAI | Google |
 |------|---------|-----------|--------|--------|
-| `reasoning` | Architecture, planning, complex decisions | inherit (Opus) | inherit | inherit |
+| `reasoning` | Architecture, planning, complex decisions | inherit (Fable/Opus) | inherit | inherit |
 | `mid` | Execution, research, verification | Sonnet | mid | mid |
 | `fast` | Read-only extraction, budget tasks | Haiku | fast | fast |
 
@@ -28,6 +28,25 @@ For backward compatibility, legacy Anthropic model names still work:
 
 ---
 
+## Recommended Models (Claude)
+
+PAN never selects your host model — it recommends one. Because the `reasoning` tier is `inherit`, whichever top-tier model you configure in your runtime (Claude Code, etc.) runs every reasoning-tier agent (planner, conductor, executor, hardener…). `mid` and `fast` agents stay on Sonnet/Haiku regardless, so the whole fleet is never on one expensive model.
+
+| Model | Role in PAN | Context | Relative cost | Notes |
+|-------|-------------|---------|---------------|-------|
+| `claude-fable-5` | **Recommended flagship** — deepest long-horizon reasoning; best for the bot army's Mission Control + planning | 1M | ~2× Opus | Runs input safety classifiers (see caveat below); requires 30-day data retention |
+| `claude-opus-4-8` | **Cost-conscious default** — same 1M context + thinking, half the cost, no cyber classifier | 1M | 1× | The safe pick when you want Opus behavior without Fable's refusal surface |
+
+**Why Fable is the recommended flagship.** It is Anthropic's most capable widely released model for demanding, long-horizon agentic work — exactly what PAN's hierarchical bot army (Mission Control → squads → workers) asks of its reasoning tier. Select it in your host runtime and `inherit` routes the reasoning-tier agents to it automatically.
+
+**Fable caveat — the cyber-classifier refusal.** Fable is the only current Claude model that runs input safety classifiers targeting cybersecurity and biology content, and benign *defensive* security tooling can trigger false positives. A block surfaces as a successful response with `stop_reason: "refusal"` and a `stop_details.category` (e.g. `cyber`). In PAN this only realistically bites the deep-review flow (`/pan:review-deep`, `exec-phase --deep-review`), where the security agents (`pan-hardener`, `pan-reviewer`, `pan-meta-reviewer`) inspect auth/crypto/injection code. Those agents are framed as **authorized, defensive review** to avoid tripping the classifier. If a review step is still refused, re-run that step on `claude-opus-4-8` — Opus does not gate requests this way.
+
+**Fable data-retention requirement.** Fable is not available under zero data retention; an org whose retention is below 30 days gets a hard `400` on every request. If Fable 400s on every call with an otherwise-valid request, check the org's retention setting before debugging anything else.
+
+**Prompting note for Fable.** Fable prefers *less-prescriptive* prompts than earlier models and runs longer per turn. PAN's autonomous-loop guidance (anti-overplanning, grounded progress claims, act-when-you-have-enough) already aligns with this; avoid piling on `CRITICAL: YOU MUST` scaffolding, which can reduce Fable's output quality.
+
+---
+
 ## Profile Definitions
 
 | Agent | `quality` | `balanced` | `budget` |