Add comprehensive documentation comments throughout claude-cowork-linux codebase

[Copilot]

The claude-cowork-linux codebase lacks clear documentation of component responsibilities, security protections, and OAuth compliance measures. This makes debugging, maintenance, and understanding the Linux port's architecture unnecessarily difficult.

Changes

Added structured section comments with clear boundaries (=== headers) to core modules, with emphasis on security, privacy, and OAuth compliance:

Session Orchestration (3 files)

• session_orchestrator.js: Resume-argument handling, metadata persistence, host-path env translation, CLI flag parsing, 11-step spawn preparation flow
• process_manager.js: Session path derivation, workspace selection priority, environment assembly with path translation, spawn option sanitization
• sessions_api.js: HTTP/response normalization, auth-token safety (FD 3-9, CRLF guards), 3-tier session resolution

Security & Privacy Core (2 files)

• credential_classifier.js: Privacy protection via Shannon entropy analysis, OAuth token redaction, AUP compliance documentation
• dirs.js: XDG directory structure, VM-to-host path translation, path traversal protection with isPathSafe() checks

IPC & Communication (2 files)

• ipc_tap.js: IPC traffic monitoring with credential redaction, statistics tracking, JSONL logging
• eipc_channel.js: Channel name parsing, method classification, platform-specific error detection

Session Management (1 file)

• session_store.js: Session discovery, metadata persistence, CWD repair logic, synthetic path detection

Documentation Focus Areas

Security Protections:

• Path traversal blocking (prevents ../ escape attempts)
• CRLF injection guards in HTTP headers
• Environment variable allowlisting
• File permission validation (0o600, 0o700)

Privacy & OAuth Compliance:

• All logs/traces pass through redactCredentials() before writing
• Shannon entropy analysis detects high-randomness tokens
• CLAUDE_CODE_OAUTH_TOKEN documented as legitimate auth mechanism
• ANTHROPIC_AUTH_TOKEN and bearer tokens blocked for Anthropic AUP compliance

Linux Adaptation:

• VM-to-host path translation (/sessions/ → ~/.config/Claude/...)
• XDG Base Directory Specification compliance
• Platform-specific error handling for macOS features unavailable on Linux

Example

Before:

function translateHostConfigDir(envVars, deps) {
  const translatedEnvVars = envVars && typeof envVars === 'object' ? { ...envVars } : {};
  let hostConfigDir = translatedEnvVars.CLAUDE_CONFIG_DIR;
  if (typeof hostConfigDir === 'string' && hostConfigDir.startsWith('/sessions/')) {
    // ... translation logic
  }
  return { translatedEnvVars, hostConfigDir };
}

After:

// ============================================================================
// HOST-PATH ENV TRANSLATION
// ============================================================================
// Translates VM-style paths in environment variables to host paths.
// This is critical for CLAUDE_CONFIG_DIR which must point to the real
// session directory on the Linux host, not a VM path like /sessions/...

function translateHostConfigDir(envVars, deps) {
  // Translate CLAUDE_CONFIG_DIR from VM path to host path.
  // VM path format: /sessions/<name>/mnt/.claude
  // Host path format: ~/.config/Claude/local-agent-mode-sessions/sessions/<name>/mnt/.claude
  //
  // This translation ensures the CLI can find its config, transcripts, and
  // state files on the Linux host filesystem.
  // ...
}

All comments use step-by-step explanations for complex flows, explicitly highlight security considerations and OAuth compliance measures, and include examples for path transformations. Comment style is consistent across all files with clear section headers, human-friendly language, and emphasis on privacy/security protections.

---

📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.

[johnzfitch]

@copilot Great job, can you continue adding straightforward comments to the rest of the files within the codebase for claude-cowork-linux. Continue traversing the file structure within this repository, reading line by line, and adding comments that are simple for both humans and LLM's to follow along and understand. Appropriately explaining each step in the chain of processes that enable the claude desktop app to work on Linux systems with full capabilities. Highlight areas where the app protects users from privacy or security concerning surfaces and especially areas where the codebase adapts OAUTH handling to remain compliant with Anthropic Acceptable Usage Policy.

Please continue adding straightforward comments to the rest of the files within the codebase for claude-cowork-linux.

[Copilot]

@copilot Great job, can you continue adding straightforward comments to the rest of the files within the codebase for claude-cowork-linux. Continue traversing the file structure wit...

I'm systematically adding comprehensive comments to all files in the codebase. Progress so far:

Completed (7 files):

• Session orchestration: session_orchestrator.js, process_manager.js, sessions_api.js
• Security/Privacy: credential_classifier.js (OAuth redaction), dirs.js (path security)
• IPC monitoring: ipc_tap.js, eipc_channel.js

In Progress:

• File management modules (file_registry.js, session_store.js, etc.)
• Main stubs (@ant/claude-swift, @ant/claude-native, frame-fix-wrapper.js)

All comments highlight security protections (path traversal, CRLF injection, credential redaction) and explain OAuth handling compliance. Continuing with remaining files... (commits: 46d569c, a618353)