chati-dev 4.0.11 → 4.1.0

package/framework/templates/brandbook-html-tmpl.md

@@ -0,0 +1,107 @@
+# Brandbook HTML Template Reference
+
+This document describes the mandatory structure for the `brandbook.html` visual style guide
+produced by the UX agent in Phase 0. Each project gets a unique brandbook.html based on its
+brand identity. This is NOT a literal HTML template to copy — it's a specification of what
+sections must exist and what each must contain.
+
+## File Requirements
+
+- **Format**: Standalone HTML5 document
+- **CSS**: All styles in a single `<style>` tag (no external stylesheets)
+- **Fonts**: Google Fonts via `<link>` tags (only external dependency allowed)
+- **JavaScript**: Minimal (only for theme toggle and smooth scroll)
+- **Output path**: `chati.dev/artifacts/4-UX/brandbook.html`
+
+## Mandatory Sections (14)
+
+### 1. Hero
+- Project name as wordmark (using the primary display font)
+- Brand tagline or description
+- Metadata: version, date, author/team
+
+### 2. Navigation
+- Sticky top bar with links to all sections
+- Backdrop blur effect
+- Active section highlighting on scroll
+
+### 3. Identity
+- Brand principles (3-5 core values)
+- Personality traits
+- Design philosophy statement
+
+### 4. Colors
+- Primary palette: visual swatches with hex, RGB, and CSS custom property name
+- Semantic colors: success, warning, error, info with swatches
+- Dark mode palette: show both themes side by side
+- Contrast ratio badges (WCAG AA pass/fail)
+
+### 5. Typography
+- Primary font: rendered specimen at all weights (300-900)
+- Secondary font: same treatment
+- Monospace font: same treatment
+- Heading scale: H1 through H6 rendered at actual sizes
+- Body text specimen
+- Line height and letter spacing values
+
+### 6. Spacing
+- Base unit and scale (4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px, 96px)
+- Visual blocks showing each spacing value
+- Named tokens (--space-xs through --space-3xl)
+
+### 7. Border Radius
+- Radius scale with visual examples on sample boxes
+- Named tokens (--radius-sm, --radius-md, --radius-lg, --radius-full)
+
+### 8. Shadows
+- Elevation levels with visual examples (shadow-sm, shadow-md, shadow-lg, shadow-xl)
+- Each shadow shown on a card element
+
+### 9. Icons
+- Selected icon library name and rationale
+- Sample icons at each size (xs, sm, md, lg, xl)
+- Usage guidelines (with text, standalone, touch targets)
+
+### 10. Components
+- Buttons: primary, secondary, ghost, destructive in all states (default, hover, active, focus, disabled)
+- Inputs: text, select, checkbox, radio in all states
+- Cards: basic, interactive, featured
+- Badges: status variants (success, warning, error, info)
+
+### 11. States
+- Loading: skeleton, spinner, progress bar patterns
+- Error: error message, error boundary, form validation
+- Empty: empty state illustration guidelines
+- Success: confirmation patterns
+
+### 12. Motion
+- Timing scale table (fast, normal, slow durations)
+- Easing curves (ease-in, ease-out, ease-in-out, spring)
+- Micro-interaction notes (hover, focus, click feedback)
+- Scroll animation personality description
+
+### 13. Accessibility
+- Contrast ratio table for all color pairs
+- WCAG AA compliance checklist
+- Focus indicator specifications
+- Reduced motion alternatives
+
+### 14. Brand Voice
+- Tone spectrum (formal to casual, technical to friendly)
+- Writing dos and donts
+- Example phrases in brand voice
+- Forbidden patterns (what the brand never says)
+
+## Visual Quality Standards
+
+- Professional design quality (minimum 8.5/10 visual polish)
+- No placeholder content (lorem ipsum, John Doe, example.com)
+- No emojis (use icons from the approved library)
+- No generic SaaS blue unless brand explicitly requires it
+- Responsive: must work on viewport widths from 375px to 1920px
+- Print: page breaks between major sections, simplified colors
+
+## Reference
+
+See `/Users/ogabrielalonso/code/focus-ai/ping/docs/brand/brandbook.html` for a production
+example with 14 sections, sticky nav, dark mode toggle, and complete token rendering.

package/framework/templates/session-memory-tmpl.yaml

@@ -0,0 +1,68 @@
+# Session Memory Template — 8-Section Structured Digest
+# Inspired by Claude Code's structured session memory (10 sections, 12K tokens).
+# Total budget: ~10K tokens (40,000 chars at 4 chars/token).
+#
+# Used by session-digest hook (PreCompact) and buildStructuredDigest() to
+# capture rich session context that survives context compaction.
+
+version: "2.0"
+
+sections:
+  - id: current_agent
+    description: "Currently active agent in the pipeline"
+    max_tokens: 100
+    priority: 1
+    required: true
+
+  - id: pipeline_position
+    description: "Current position in the DISCOVER→PLAN→BUILD→DEPLOY pipeline"
+    max_tokens: 100
+    priority: 2
+    required: true
+
+  - id: active_task
+    description: "Active task ID, title, and acceptance criteria (Given-When-Then)"
+    max_tokens: 500
+    priority: 3
+    required: false
+
+  - id: files_changed
+    description: "Files created, modified, or deleted during this session"
+    max_tokens: 1000
+    priority: 7
+    required: false
+
+  - id: blockers
+    description: "Active blockers preventing progress (C01-C15 code, G01-G08 general)"
+    max_tokens: 1000
+    priority: 4
+    required: false
+
+  - id: decisions_made
+    description: "Key decisions with rationale (what + why) made during session"
+    max_tokens: 3000
+    priority: 5
+    required: false
+
+  - id: gotchas_found
+    description: "Error patterns and gotchas discovered during session"
+    max_tokens: 2000
+    priority: 6
+    required: false
+
+  - id: next_steps
+    description: "Planned next steps and pending actions"
+    max_tokens: 2300
+    priority: 8
+    required: false
+
+total_budget_tokens: 10000
+
+truncation_order:
+  - next_steps
+  - gotchas_found
+  - files_changed
+  - blockers
+  - decisions_made
+  - active_task
+  # current_agent and pipeline_position are never truncated

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chati-dev",
-  "version": "4.0.11",
+  "version": "4.1.0",
   "description": "AI-Powered Multi-Agent Orchestration System — Structured vibe coding for Full Stack Development",
   "type": "module",
   "bin": {

package/src/autonomy/build-state.js

@@ -131,7 +131,7 @@ export function loadBuildState(projectDir) {
     }
 
     return state;
-  } catch {
+  } catch { /* expected: operation may fail gracefully */
     return null;
   }
 }

package/src/autonomy/worktree-manager.js

@@ -64,7 +64,7 @@ export function isGitRepo(dir) {
   try {
     git('rev-parse --is-inside-work-tree', dir);
     return true;
-  } catch {
+  } catch { /* expected: content may be malformed */
     return false;
   }
 }
@@ -100,7 +100,7 @@ export function createWorktree(projectDir, taskId, attempt) {
   if (existsSync(worktreePath)) {
     try {
       git(`worktree remove "${worktreePath}" --force`, absProject);
-    } catch {
+    } catch { /* expected: operation may fail gracefully */
       rmSync(worktreePath, { recursive: true, force: true });
     }
   }
@@ -108,7 +108,7 @@ export function createWorktree(projectDir, taskId, attempt) {
   // Delete branch if it exists from a previous run
   try {
     git(`branch -D "${branch}"`, absProject);
-  } catch {
+  } catch { /* expected: operation may fail gracefully */
     // Branch doesn't exist — fine
   }
 
@@ -118,12 +118,12 @@ export function createWorktree(projectDir, taskId, attempt) {
   const cleanup = () => {
     try {
       git(`worktree remove "${worktreePath}" --force`, absProject);
-    } catch {
+    } catch { /* expected: operation may fail gracefully */
       // Worktree already removed — ignore
     }
     try {
       git(`branch -D "${branch}"`, absProject);
-    } catch {
+    } catch { /* expected: operation may fail gracefully */
       // Branch already deleted — ignore
     }
   };
@@ -146,7 +146,7 @@ export function mergeWorktree(projectDir, worktreeBranch, mainBranch) {
   if (!mainBranch) {
     try {
       mainBranch = git('rev-parse --abbrev-ref HEAD', absProject);
-    } catch {
+    } catch { /* expected: content may be malformed */
       mainBranch = 'main';
     }
   }
@@ -154,7 +154,7 @@ export function mergeWorktree(projectDir, worktreeBranch, mainBranch) {
   // Ensure we're on the main branch
   try {
     git(`checkout "${mainBranch}"`, absProject);
-  } catch {
+  } catch { /* expected: operation may fail gracefully */
     return { success: false, conflicts: [`Failed to checkout ${mainBranch}`] };
   }
 
@@ -162,7 +162,7 @@ export function mergeWorktree(projectDir, worktreeBranch, mainBranch) {
   try {
     git(`merge "${worktreeBranch}" --no-edit`, absProject);
     return { success: true, conflicts: [] };
-  } catch {
+  } catch { /* expected: operation may fail gracefully */
     // Parse conflicts from error output
     const conflicts = [];
     try {
@@ -170,14 +170,14 @@ export function mergeWorktree(projectDir, worktreeBranch, mainBranch) {
       if (status) {
         conflicts.push(...status.split('\n').filter(Boolean));
       }
-    } catch {
+    } catch { /* expected: operation may fail gracefully */
       conflicts.push('Unknown conflict — check git status');
     }
 
     // Abort the failed merge
     try {
       git('merge --abort', absProject);
-    } catch {
+    } catch { /* expected: operation may fail gracefully */
       // Already aborted or not in merging state
     }
 
@@ -207,7 +207,7 @@ export function cleanupWorktrees(projectDir, options = {}) {
   let entries;
   try {
     entries = readdirSync(worktreeBase);
-  } catch {
+  } catch { /* expected: directory may not exist */
     return { cleaned, errors: ['Failed to read worktree directory'] };
   }
 
@@ -222,7 +222,7 @@ export function cleanupWorktrees(projectDir, options = {}) {
       if (age > maxAge) {
         try {
           git(`worktree remove "${entryPath}" --force`, absProject);
-        } catch {
+        } catch { /* expected: operation may fail gracefully */
           rmSync(entryPath, { recursive: true, force: true });
         }
 
@@ -230,7 +230,7 @@ export function cleanupWorktrees(projectDir, options = {}) {
         const branch = `chati/${entry}`;
         try {
           git(`branch -D "${branch}"`, absProject);
-        } catch {
+        } catch { /* expected: operation may fail gracefully */
           // Branch already deleted
         }
 

package/src/config/agent-customizer.js

@@ -80,7 +80,7 @@ export function loadCustomization(projectDir, agentName) {
     }
 
     return { found: true, overrides };
-  } catch {
+  } catch { /* expected: content may be malformed */
     return { found: false, overrides: {} };
   }
 }

package/src/config/gemini-hooks-generator.js

@@ -93,7 +93,7 @@ async function main() {
     }
 
     console.log(JSON.stringify({}));
-  } catch {
+  } catch { /* expected: operation may fail gracefully */
     console.log(JSON.stringify({}));
   }
 }
@@ -149,7 +149,7 @@ async function main() {
     }
 
     console.log(JSON.stringify({}));
-  } catch {
+  } catch { /* expected: operation may fail gracefully */
     console.log(JSON.stringify({}));
   }
 }
@@ -236,7 +236,7 @@ async function main() {
         error: \`[Article XI] Cannot write "\${filePath}" in \${mode} mode. Allowed: \${MODE_SCOPES[mode].allowed.join(', ')}\`
       }));
     }
-  } catch {
+  } catch { /* expected: operation may fail gracefully */
     console.log(JSON.stringify({}));
   }
 }
@@ -331,7 +331,7 @@ async function main() {
     }
 
     console.log(JSON.stringify({}));
-  } catch {
+  } catch { /* expected: operation may fail gracefully */
     console.log(JSON.stringify({}));
   }
 }
@@ -411,7 +411,7 @@ async function main() {
     }
 
     console.log(JSON.stringify({}));
-  } catch {
+  } catch { /* expected: operation may fail gracefully */
     console.log(JSON.stringify({}));
   }
 }
@@ -450,7 +450,7 @@ async function main() {
     }
 
     console.log(JSON.stringify({}));
-  } catch {
+  } catch { /* expected: operation may fail gracefully */
     console.log(JSON.stringify({}));
   }
 }

package/src/config/ide-configs.js

@@ -39,7 +39,7 @@ export const IDE_CONFIGS = {
   },
   'vscode': {
     name: 'VS Code',
-    description: 'Extensions: Continue, Copilot Chat, etc',
+    description: 'Extensions: Continue, AI Chat, etc',
     group: 'editor',
     recommended: false,
     configPath: '.vscode/chati/',

package/src/context/bracket-tracker.js

@@ -18,7 +18,7 @@
  *   CRITICAL = 5.0% → maximum reinforcement (last interactions before handoff)
  */
 
-import { PROVIDER_LIMITS } from '../utils/provider-limits.js';
+import { resolveContextLimit } from '../utils/provider-limits.js';
 import { BRACKETS } from '../utils/brackets.js';
 
 /**
@@ -40,9 +40,10 @@ const MEMORY_LEVELS = {
  * Calculate bracket from remaining context percentage.
  * @param {number} remainingPercent - 0 to 100
  * @param {string} [provider='claude'] - Provider name for context window scaling
+ * @param {string} [model] - Model tier (opus, sonnet, haiku) for precise context limits
  * @returns {{ bracket: string, activeLayers: string[], tokenBudget: number, budgetRatio: number, memoryLevel: string, handoffRequired: boolean, provider: string }}
  */
-export function calculateBracket(remainingPercent, provider = 'claude') {
+export function calculateBracket(remainingPercent, provider = 'claude', model) {
   const pct = Math.max(0, Math.min(100, remainingPercent));
 
   let name = 'CRITICAL';
@@ -51,8 +52,8 @@ export function calculateBracket(remainingPercent, provider = 'claude') {
   else if (pct >= 25) name = 'DEPLETED';
 
   const def = BRACKETS[name];
-  const providerLimit = PROVIDER_LIMITS[provider] || PROVIDER_LIMITS.claude;
-  const tokenBudget = Math.round(def.budgetRatio * providerLimit);
+  const contextLimit = resolveContextLimit(model, provider);
+  const tokenBudget = Math.round(def.budgetRatio * contextLimit);
 
   return {
     bracket: name,
@@ -90,6 +91,26 @@ export function isLayerActive(bracket, layer) {
   return def.layers.includes(layer);
 }
 
+/**
+ * Estimate remaining context percentage from actual prompt content size.
+ * Uses the heuristic that 1 token ≈ 4 characters.
+ *
+ * This is more accurate than turn-count estimation because it measures
+ * actual content rather than guessing from conversation length.
+ *
+ * @param {string} promptText - The full prompt text to estimate
+ * @param {string} [provider='claude'] - Provider name for context window scaling
+ * @param {string} [model] - Model tier (opus, sonnet, haiku) for precise limits
+ * @returns {number} Estimated remaining percentage (0-100)
+ */
+export function estimateRemainingFromTokens(promptText, provider = 'claude', model) {
+  if (!promptText) return 100;
+  const estimatedTokens = Math.ceil(promptText.length / 4);
+  const limit = resolveContextLimit(model, provider);
+  const used = Math.min(estimatedTokens, limit) / limit;
+  return Math.round((1 - used) * 100);
+}
+
 /**
  * Get all bracket definitions (for display/dashboard).
  * @returns {Record<string, { min: number, max: number, layers: string[], tokenBudget: number }>}

package/src/context/engine.js

@@ -18,6 +18,14 @@ import { formatContext } from './formatter.js';
 
 const LAYER_TIMEOUT_MS = 100;
 
+/**
+ * Static cache for L0+L1 layers.
+ * These layers never change mid-session (constitution and global rules are stable),
+ * so we cache them to improve prompt cache hit rates.
+ * Inspired by Claude Code's SYSTEM_PROMPT_DYNAMIC_BOUNDARY pattern.
+ */
+let _staticCache = { key: null, l0: null, l1: null };
+
 /**
  * Run the PRISM context engine pipeline.
  *
@@ -61,14 +69,29 @@ export function runPrism(input) {
   // 3. Process each active layer with timeout protection
   const layerResults = {};
 
-  // L0 — Always active
-  const l0 = safeProcess('L0', () => processL0(ctx), errors);
-  if (l0) { layers.push(l0); layerResults.l0 = l0; }
+  // L0 + L1 — Static layers (cacheable, never change mid-session)
+  const cacheKey = `${input.domainsDir || ''}:${ctx.mode}`;
+  if (_staticCache.key === cacheKey && _staticCache.l0) {
+    layerResults.l0 = _staticCache.l0;
+    layers.push(_staticCache.l0);
+    if (_staticCache.l1) {
+      layerResults.l1 = _staticCache.l1;
+      layers.push(_staticCache.l1);
+    }
+  } else {
+    // L0 — Always active
+    const l0 = safeProcess('L0', () => processL0(ctx), errors);
+    if (l0) { layers.push(l0); layerResults.l0 = l0; }
+
+    // L1 — Always active
+    let l1 = null;
+    if (isLayerActive(bracket.bracket, 'L1')) {
+      l1 = safeProcess('L1', () => processL1(ctx), errors);
+      if (l1) { layers.push(l1); layerResults.l1 = l1; }
+    }
 
-  // L1 — Always active
-  if (isLayerActive(bracket.bracket, 'L1')) {
-    const l1 = safeProcess('L1', () => processL1(ctx), errors);
-    if (l1) { layers.push(l1); layerResults.l1 = l1; }
+    // Cache static layers
+    _staticCache = { key: cacheKey, l0: layerResults.l0 || null, l1: l1 };
   }
 
   // L2 — Agent layer
@@ -132,6 +155,13 @@ function safeProcess(layerName, processFn, errors) {
   }
 }
 
+/**
+ * Clear the static L0+L1 cache. Used when mode changes or for testing.
+ */
+export function clearStaticCache() {
+  _staticCache = { key: null, l0: null, l1: null };
+}
+
 /**
  * Get a summary of PRISM capabilities for display.
  * @returns {{ layers: number, brackets: string[], features: string[] }}

package/src/context/formatter.js

@@ -52,7 +52,19 @@ export function formatContext(options) {
     sections.push(formatKeywords(l5));
   }
 
-  let body = sections.join('\n\n');
+  // Insert STATIC_BOUNDARY between static (L0+L1) and dynamic (L2-L5) sections.
+  // This enables prompt cache reuse for the stable prefix (Claude Code pattern).
+  const staticSections = sections.slice(0, l1 ? 2 : (l0 ? 1 : 0));
+  const dynamicSections = sections.slice(staticSections.length);
+
+  let body;
+  if (dynamicSections.length > 0) {
+    body = staticSections.join('\n\n') +
+      '\n\n  <!-- STATIC_BOUNDARY -->\n\n' +
+      dynamicSections.join('\n\n');
+  } else {
+    body = staticSections.join('\n\n');
+  }
 
   // Truncate if over budget (rough estimate: 1 token ≈ 4 chars)
   const maxChars = tokenBudget * 4;
@@ -193,6 +205,38 @@ function truncateByPriority(sections, maxChars) {
   return result;
 }
 
+/**
+ * Format only the static portion (L0 + L1) of the context.
+ * Useful for caching the stable prefix separately.
+ * @param {object} l0 - L0 Constitution result
+ * @param {object} [l1] - L1 Global result
+ * @returns {string} Static XML block
+ */
+export function formatStaticBlock(l0, l1) {
+  const parts = [];
+  if (l0) parts.push(formatConstitution(l0));
+  if (l1) parts.push(formatGlobal(l1));
+  return parts.join('\n\n');
+}
+
+/**
+ * Format only the dynamic portion (L2-L5) of the context.
+ * Changes every turn based on agent, workflow, task, and keywords.
+ * @param {object} [l2] - L2 Agent result
+ * @param {object} [l3] - L3 Workflow result
+ * @param {object} [l4] - L4 Task result
+ * @param {object} [l5] - L5 Keywords result
+ * @returns {string} Dynamic XML block
+ */
+export function formatDynamicBlock(l2, l3, l4, l5) {
+  const parts = [];
+  if (l2 && l2.agent) parts.push(formatAgent(l2));
+  if (l3 && l3.workflow) parts.push(formatWorkflow(l3));
+  if (l4 && l4.taskId) parts.push(formatTask(l4));
+  if (l5 && l5.matchCount > 0) parts.push(formatKeywords(l5));
+  return parts.join('\n\n');
+}
+
 /** Escape XML special characters */
 function esc(str) {
   if (!str) return '';

package/src/context/index.js

@@ -1,4 +1,4 @@
-export { runPrism, getPrismInfo } from './engine.js';
-export { calculateBracket, estimateRemaining, isLayerActive, getBracketDefinitions } from './bracket-tracker.js';
-export { formatContext } from './formatter.js';
+export { runPrism, getPrismInfo, clearStaticCache } from './engine.js';
+export { calculateBracket, estimateRemaining, estimateRemainingFromTokens, isLayerActive, getBracketDefinitions } from './bracket-tracker.js';
+export { formatContext, formatStaticBlock, formatDynamicBlock } from './formatter.js';
 export { loadDomainFile, loadAgentDomains, loadWorkflowDomains, extractRules } from './domain-loader.js';

package/src/dashboard/data-reader.js

@@ -25,7 +25,7 @@ export async function readDashboardData(targetDir) {
   if (existsSync(sessionPath)) {
     try {
       data.session = yaml.load(readFileSync(sessionPath, 'utf-8'));
-    } catch {
+    } catch { /* expected: file may not exist */
       data.session = null;
     }
   }
@@ -35,7 +35,7 @@ export async function readDashboardData(targetDir) {
   if (existsSync(configPath)) {
     try {
       data.config = yaml.load(readFileSync(configPath, 'utf-8'));
-    } catch {
+    } catch { /* expected: file may not exist */
       data.config = null;
     }
   }
@@ -64,7 +64,7 @@ export async function readDashboardData(targetDir) {
     try {
       const files = readdirSync(tasksDir).filter(f => f.endsWith('.yaml') || f.endsWith('.md'));
       data.taskProgress = { totalFiles: files.length };
-    } catch {
+    } catch { /* expected: directory may not exist */
       // Ignore
     }
   }
@@ -75,7 +75,7 @@ export async function readDashboardData(targetDir) {
     try {
       const gotchasData = yaml.load(readFileSync(gotchasPath, 'utf-8'));
       data.gotchas = gotchasData?.gotchas || [];
-    } catch {
+    } catch { /* expected: file may not exist */
       // Ignore
     }
   }
@@ -102,21 +102,21 @@ export async function readDashboardData(targetDir) {
   try {
     const { getMemoryStats } = await import('../intelligence/memory-manager.js');
     data.memoryStats = getMemoryStats(targetDir);
-  } catch {
+  } catch { /* expected: operation may fail gracefully */
     // Intelligence module not available
   }
 
   try {
     const { getContextStatus } = await import('../intelligence/context-status.js');
     data.contextStatus = getContextStatus(targetDir);
-  } catch {
+  } catch { /* expected: operation may fail gracefully */
     // Intelligence module not available
   }
 
   try {
     const { getRegistryStats } = await import('../intelligence/registry-manager.js');
     data.registryStats = getRegistryStats(targetDir);
-  } catch {
+  } catch { /* expected: operation may fail gracefully */
     // Intelligence module not available
   }
 

package/src/decision/engine.js

@@ -168,7 +168,7 @@ export function getDecisionHistory(projectDir) {
     const content = readFileSync(historyPath, 'utf8');
     const data = JSON.parse(content);
     return data.decisions || [];
-  } catch {
+  } catch { /* expected: file may not exist */
     return [];
   }
 }
@@ -193,7 +193,7 @@ export function recordDecision(projectDir, decision) {
     try {
       const content = readFileSync(historyPath, 'utf8');
       history = JSON.parse(content);
-    } catch {
+    } catch { /* expected: file may not exist */
       // Keep empty history if parse fails
     }
   }

package/src/decision/registry-healer.js

@@ -439,7 +439,7 @@ export function applyFixes(projectDir, fixes) {
           applied++;
           break;
       }
-    } catch {
+    } catch { /* expected: operation may fail gracefully */
       // Skip failed fixes
     }
   });

package/src/decision/registry-updater.js

@@ -290,7 +290,7 @@ export function generateEntityMeta(projectDir, filePath) {
         .slice(0, 5)
         .map(([word]) => word);
       meta.keywords.push(...topWords);
-    } catch {
+    } catch { /* expected: operation may fail gracefully */
       // Ignore read errors
     }
   }
@@ -322,7 +322,7 @@ function scanDirectory(dirPath) {
         files.push(fullPath);
       }
     });
-  } catch {
+  } catch { /* expected: operation may fail gracefully */
     // Ignore read errors
   }