Centralize filename generation into FilenameBuilder class

[djdarcy]

Summary

Centralize all log filename generation into a single FilenameBuilder class to prevent naming divergence bugs and enable future configurability.

Background

Issue #15 revealed that having two independent filename generation functions (get_filename_context() and get_task_filename_context()) with slightly different separator conventions (_ vs __ before username) caused an infinite file proliferation cycle — 119+ files per session instead of one.

The immediate fix (removing get_task_filename_context()) solves the bug, but the broader architectural risk remains: filename strings are currently constructed in multiple independent locations that can drift apart.

Current State

Filename generation is spread across:

Location	Purpose	Separator before user
get_filename_context()	Write path for sesslog/shell	_
get_task_filename_context()	Write path for tasks (being removed in #15 fix)	__
build_filename()	Reconciliation target naming	_
_get_channel_path()	Channel-based routing write path	delegates to above
find_session_files() regex	File detection/scanning	matches both via \w+
extract_session_name_from_file() regex	Name extraction from filenames	anchors on __{session_id}
find_max_sequence() regex	Sequence number detection	hardcoded pattern
Directory naming in reconcile_session_directory()	{name}__{guid}_{user}	_

Proposal

Create a FilenameBuilder class that:

1. Is the single source of truth for all filename construction — write paths, reconciliation targets, and regex patterns all derive from the same format specification
2. Encapsulates the format convention (separator characters, field ordering, sequence number format) in one place
3. Generates matching regex patterns from the same format spec, so detection always matches what generation produces
4. Could be configurable via the settings system (Feature: User-configurable logging channels and file routing #1, Configuration System Architecture & JSON Schema #12) — e.g., users who want less verbose filenames, or prefer __ as a universal separator

Possible API sketch

class FilenameBuilder:
    """Centralized log filename construction."""

    def __init__(self, shell: str, session_name: str, session_id: str, username: str):
        self.shell = shell
        self.session_name = session_name
        self.session_id = session_id
        self.username = username

    def build(self, prefix: str, file_type: str, seq: int = None) -> str:
        """Build a filename. Used by both write paths and reconciliation."""
        ...

    def match_pattern(self, prefix: str, file_type: str) -> re.Pattern:
        """Return regex that matches any file this builder could produce."""
        ...

    def extract_name(self, filename: str) -> Optional[str]:
        """Extract session name from a filename."""
        ...

Value

• Eliminates the class of bug where write paths and reconciliation paths diverge
• Single place to update if filename format changes
• Enables future user-configurable filename formats
• Reduces regex duplication (5+ hand-written patterns → generated from format spec)

Related

• Task file proliferation: 100+ files per session instead of one #15: Task file proliferation (the bug this prevents from recurring)
• Feature: User-configurable logging channels and file routing #1: User-configurable logging channels (filename format could be a config option)
• Configuration System Architecture & JSON Schema #12: Configuration System Architecture
• See 2026-02-11__21-27-39__task-file-proliferation-analysis.md for root cause analysis